<!DOCTYPE html> 

<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>ROS with IEC 61499 Tutorial</title>
	<link rel="stylesheet" type="text/css" href="../help.css">
</head>

<body>
<h1 id="topOfPage">How to use 4DIAC's ROS Communication Interface</h1>
<p>

4DIAC supports ROS communication for ROS topics, services and actions. ROS
topics have been implemented as a communication layer in FORTE, whereas
services and actions require customized ROS function blocks. The implementation
was tested with ROS indigo and on Ubuntu 14.04. Other versions (ROS or Ubuntu)
might cause problems during the execution of the ROS 4DIAC communication interface.

The Example service and action FBs can be used to implement your own IEC 61499
compliant communication FBs for the datatypes you need. The ROS communication layer
for topics can easily be extended by adding the IEC61499-ROS mapping of other
datatypes.

</p>

<p>Prerequisites:</p>
<ol>
	<li>ROS indigo installed on Ubuntu 14.04.</li>
	<li>4DIAC-IDE installed</li>
	<li>CMake</li>
</ol>


<h2 id="build">How to Build FORTE with ROS Functionalities</h2>
<!--TODO remove setup_posix script and show all cmake variables that have to be set
Perform the following steps to build forte with ROS communication support:-->
<ol>
<li> Clone forte and switch to the develop branch
<div class="code">$ git clone git://git.eclipse.org/gitroot/4diac/org.eclipse.4diac.forte.git
$ cd org.eclipse.4diac.forte
$ git checkout develop</div></li>
<li> Source indigo installation and start cmake from this "sourced" command line:
<div class="code">$ source /opt/ros/indigo/setup.bash
$ cmake-gui</div></li>
<li> Press "configure" and set the appropriate CMake variables
<div class="code">FORTE_ARCHITECTURE=Posix
CMAKE_BUILD_TYPE=Debug
FORTE_MODULE_ROS=On
FORTE_RTTI_AND_EXCEPTIONS=TRUE
</div></li>
<li>After that press "configure" again until the red fields disappear and then press "generate" and build forte with:
<div class="code">$ cd "/path/to/your/forte/build/directory"
$ make
</div></li>
<li>Source your workspace (in the command line where you want to start forte) and start a ROS core (on a different command line):
<div class="code">$ source "/path/to/your/forte/build/directory"/devel/setup.bash

$ roscore</div></li>
<li> Start forte:
<div class="code">$ cd [/path/to/your/forte/build/directory]/src
$ ./forte</div>
</li>

</ol>

<h2 id="topics">ROS Topics</h2>

<p>
4DIAC implements a Communication Layer for standard ROS topics. Use the
PUBLISH_0 / SUBSCRIBE_0 and PUBLISH_1 / SUBSCRIBE_1 function blocks with the
following datatypes:

</p>


<table>
  <tr>
    <th>ROS</th>
    <th>IEC61499</th>
  </tr>
  <tr>
    <td>std_msgs/Empty</td>
    <td> - (empty)</td>
  </tr>
  <tr>
    <td>std_msgs/Float64</td>
    <td>LREAL</td>
  </tr>
  <tr>
    <td>std_msgs/Bool</td>
    <td>BOOL</td>
  </tr>
  <tr>
    <td>std_msgs/Int32</td>
    <td>DINT</td>
  </tr>
  <tr>
    <td>std_msgs/String</td>
    <td>STRING</td>
  </tr>
</table>


<p>
The ID data input for a communication layer contains the protocol and a string of vendor
specific parameters and looks like this:</p>

<pre>protocol[parameter]</pre>

<p>In our case the protocol string is ros. the parameters in square brackets are a ROS-topic
namespace and/or name and its corresponding ROS message type, separated by a colon. In
general the ID for a ROS publish or subscribe function block looks like this:</p>

<pre>ros[topic_name:message_name]</pre>

<p>An example of a ROS publish and subscribe connection within FORTE is shown next.</p>

<img src="../../html/communication/img/topics_example.PNG" alt="Example Application using publish and subscribe to send and receive ROS topics"/>

<h2 id="services">ROS Services</h2>

The current implementation of ROS Services is limited to a single service type which is
<a href="http://docs.ros.org/kinetic/api/std_srvs/html/srv/Trigger.html">std_srvs/Trigger</a>.
This service client and server function block can be used as a template to implement the
ROS communication function blocks for your specific application. The interfaces of the
trigger service client and server are shown next.
<br/>
<img src="../../html/communication/img/fb_trigger_service.PNG" alt="Interface of the Trigger Service Server and Client SIFB"/>
<br/>

A brief Interface description is given by the next 2 tables that show event and data connections of the implemented
ROS function blocks.
<br/>

<table>
  <tr>
    <th>Event Name</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>CLIENT</td>
    <td></td>
  </tr>
  <tr>
    <td>INIT+</td>
    <td>Initialize Client FB</td>
  </tr>
  <tr>
    <td>INIT-</td>
    <td>Terminate Client FB</td>
  </tr>
  <tr>
    <td>REQ</td>
    <td>Send a ROS service request to the connected server</td>
  </tr>
  <tr>
    <td>CNF</td>
    <td>Client FB successfully received a response from the server</td>
  </tr>
  <tr>
    <td>SERVER</td>
    <td></td>
  </tr>
  <tr>
    <td>INIT+</td>
    <td>Initialize Server FB</td>
  </tr>
  <tr>
    <td>INIT-</td>
    <td>Terminate Server FB</td>
  </tr>
  <tr>
    <td>IND</td>
    <td>Server FB received a request from the connected client</td>
  </tr>
  <tr>
    <td>RSP</td>
    <td>Send a response to the client (e.g. when the FBN finished processing the request)</td>
  </tr>
</table>

<br/>

<table>
  <tr>
    <th>Data Name</th>
    <th>Data Type</th>
	<th>Description</th>
  </tr>
  <tr>
    <td>QI</td>
    <td>BOOL</td>
	<td>Qualifier input</td>
  </tr>
  <tr>
    <td>NAMESPACE</td>
    <td>STRING</td>
	<td>Namespace of the service</td>
  </tr>
  <tr>
    <td>SRVNAME</td>
    <td>STRING</td>
	<td>Name of the service</td>
  </tr>
  <tr>
    <td>QO</td>
    <td>BOOL</td>
	<td>Qualifier output</td>
  </tr>
  <tr>
    <td>STATUS</td>
    <td>STRING</td>
	<td>Status of the FB</td>
  </tr>
  <tr>
    <td>SUCCESS</td>
    <td>BOOL</td>
	<td>Value related to response.success in std_srvs/Trigger.srv</td>
  </tr>
  <tr>
    <td>MESSAGE</td>
    <td>STRING</td>
	<td>Value related to response.message in std_srvs/Trigger.srv</td>
  </tr>
</table>

<h2 id="actions">ROS Actions</h2>
<p>
The ROS action type which is currently supported by 4DIAC is reapp_msgs/Execute.action. Its definition
is shown next.
</p>

<pre>
#goal
string command
int32 id1
int32 id2
---
#result
string result
int32 id
---
#feedback
string state
</pre>

<p>
You can install this action on Ubuntu 14.04 running ROS indigo via:
</p>
<pre>
sudo apt-get install ros-indigo-reapp-msgs
</pre>
<p>
The interface of the client and server FBs is shown in the following figure and described in the diagrams below:

<br/>
<img src="../../html/communication/img/fb_execute_action.PNG" alt="Interface of the ExecuteAction Server and Client SIFB"/>
<br/>

</p>
<table>
  <tr>
    <td>Event Name</td>
    <td>Description</td>
  </tr>
  <tr>
    <td>CLIENT</td>
    <td></td>
  </tr>
  <tr>
    <td>INIT+</td>
    <td>Initialize Client FB</td>
  </tr>
  <tr>
    <td>INIT-</td>
    <td>Terminate Client FB</td>
  </tr>
  <tr>
    <td>REQ+</td>
    <td>Send a ROS action goal to the connected server</td>
  </tr>
  <tr>
    <td>REQ-</td>
    <td>Cancel the current ROS action goal to the connected server</td>
  </tr>
  <tr>
    <td>CNF+</td>
    <td>Client FB received a result from the server</td>
  </tr>
  <tr>
    <td>CNF-</td>
    <td>Client FB received feedback from the server</td>
  </tr>
  <tr>
    <td>SERVER</td>
    <td></td>
  </tr>
  <tr>
    <td>INIT+</td>
    <td>Initialize Server FB</td>
  </tr>
  <tr>
    <td>INIT-</td>
    <td>Terminate Server FB</td>
  </tr>
  <tr>
    <td>IND</td>
    <td>Server FB received a goal from the connected client</td>
  </tr>
  <tr>
    <td>RSP+</td>
    <td>Send the result to the client (e.g. when the FBN finished processing the goal)</td>
  </tr>
  <tr>
    <td>RSP-</td>
    <td>Send feedback to the client (e.g. intermediate results during processing)</td>
  </tr>
</table>
<br/>
the data in and outputs of the execute action FBs can be described as shown next:
<br/>
<table>
  <tr>
    <td>Data Name</td>
    <td>Data Type</td>
	<td>Description</td>
  </tr>
  <tr>
    <td>QI</td>
    <td>BOOL</td>
	<td>Qualifier input</td>
  </tr>
  <tr>
    <td>ACTIONNAMESPACE</td>
    <td>STRING</td>
	<td>Namespace of the action</td>
  </tr>
  <tr>
    <td>ACTIONMSGNAME</td>
    <td>STRING</td>
	<td>Name of the action</td>
  </tr>
  <tr>
    <td>COMMAND</td>
    <td>STRING</td>
	<td>Value related to goal.command in reapp_msgs/Execute.action</td>
  </tr>
  <tr>
    <td>ID1</td>
    <td>DINT</td>
	<td>Value related to goal.id1 in reapp_msgs/Execute.action</td>
  </tr>
  <tr>
    <td>ID2</td>
    <td>DINT</td>
	<td>Value related to goal.id2 in reapp_msgs/Execute.action</td>
  </tr>
  <tr>
    <td>QO</td>
    <td>BOOL</td>
	<td>Qualifier output</td>
  </tr>
  <tr>
    <td>FBSTATUS</td>
    <td>STRING</td>
	<td>Status of the FB</td>
  </tr>
  <tr>
	<td>ACTIONSTATUS</td>
	<td>STRING</td>
	<td>Status of the action server</td>
  </tr>
  <tr>
    <td>RESULT</td>
    <td>STRING</td>
	<td>Value related to result.result in reapp_msgs/Execute.action</td>
  </tr>
  <tr>
    <td>ID</td>
    <td>DINT</td>
	<td>Value related to result.id in reapp_msgs/Execute.action</td>
  </tr>
  <tr>
    <td>STATE</td>
    <td>STRING</td>
	<td>Value related to feedback.state in std_srvs/Trigger.srv</td>
  </tr>
</table>

<br/>

A typical workflow with the execute action client would be to initialize it (INIT+),
synchronise the appropriate data for the goal and send the goal (REQ+).
When the goal is processed at the server the server may (depending on the implmentation)
send feedback to the client. This feedback is recognized by the block via a negative confirm
(CNF-). As soon as the server sends the result the client will get the result that is
synchronized at the RESULT and ID data outputs of the function block and a positive confirm
is triggered (CNF+).

Testing and debugging of the action server and client can easily be done with the axserver/
axclient provided by ROS. An axserver that connects to an execute action client within 4DIAC
with the configuration

<pre>ACTIONNAMESPACE=test_execute
ACTIONMSGNAME=localisation</pre>

can be started like this:

<pre>rosrun actionlib axserver.py test_execute/localisation reapp_msgs/ExecuteAction</pre>

<h1>Where to go from here?</h1>

<p>Go back to Protocols index:</p>

<p><a href="../../html/communication/communicationIndex.html">Communication Index</a></p>

<p>If you want to go back to the Start Here page, we leave you here a fast access</p>

<p><a href="../../html/startHere/startHere.html">Start Here page</a></p>

<p class="goToTop">Or <a href="#topOfPage">Go to top</a></p>

</body>
</html>